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1.0 Introduction a . oe iE 
1.1 Scope Be a Se eR. tee ee Pacis 


This documents the CDI user interfaces to system libraries 


using library utilities. This one necessary to access or 


7 generate library modules and manipulate the library is 
contained here. 7 - 5 
The MIRAM library modules supported for the current 
release /((R7. are: 7S . een : | 
o Saved run library modules | 
@ - > ° screen format modules 


The SAT library modules supported for the current release 


are: , 2 


, 


o .source ~ 


© proc. © 
5 ee . 
No CBTET 

LOAD 
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Functions Available | 

The system library interface allows user programs to 
access directly any System library file. These functions 
are provided: 00-2. s- 
__.0 .reading a library module 
“_o, creating a library module 
© deleting a library module 


o interrogating a library directory 
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2.1.1 anterface Macros-- =... 


The CDI macros ‘are the only ones used to interface 
with libraries (thru library utilities). Both imperative 
and declarative macros are used. The imperatives are: 


o OPEN - data management file OPEN 


‘ o CLOSE - data management file CLOSE 
o DMINP - retrieve a library record ~ pd ? 
o DMOUT - write a library record - ‘eke 5 on ie 


o DMSEL - initialize a library operation (Gsually) - 
@. The declaratives are: 


? cpIB . peeeeey. operation control block ie 


a me) ‘RIB - used only at OPEN (as per data management) 
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Flow of Control 


The CDIB (as defined by data management) is the basic 


- controlling block used by library utilities. It is used 


to communicate between the user program and the utilities. 
It is specified on each imperative macro and will contain 


status on return. 


The user starts by issuing an OPEN imperative to a CDIB 


which identifies the library file involved (by LFD). 


This is a standard data management requirement. 
v : “ 


The next step depends upon what kind of operation the 


user wants to do. The operations available are described 


in Section 2.2 ana assume the CDIB is already open. The 


~ 


flow of most operations is: é 
P l. DMSEL - initialize (or identify) operation 
2. DMINP/DMOUT - retrieve or present data 


Be DMSEL ~— terminate operation 


: This is an outline of a typical operation. Step 2 wili 


; probably be executed more than once. Step 3 is not always 


required.. pe . 


The user must issue a CLOSE imperative macro for each 


CDIB active before the program terminates. 
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Sy ae . Reading and Writing Tibeacy. oueautee: ; : 
- This interface allows ‘the. user-to read or write library 


modules a record at a time. “Records of a “‘Library- module 
are passed between library eeqiexes and ne user program 


as a result of a DMINP or DMOUT Haeee Aneteuction<= © 
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Reading a Library Module eo 


_-This sequence of imperative macros is required: -.. 


(o) rae . a Se Sas 
EDEMERTE : 
NEXT a a mone 


Bau (0) - 
2. DMINP cdib, 
i. workarea 


DMSEL initializes the operation by locating the module 


“and returning the header record in the data buffer 


(IOAREA1). Two types of operation are permitted: 

o° select element of specified name and type 

© select the next sequential element in file, 
DMINP moves data records to the user buffer. The 
user issues as many of these ~ required. When the 
modules is syns asad: an end of data condition is set 


ac 


in the CDIB. 
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Writing a Library Module 
This sequence of macros is_required: 
- ae ow 2 
1. DMSEL edib, 16, OUT, BREMENT=nemeyP¥PB=type 
‘ ; . 7 g 
= 2. DMOUT cdib, | workarea 


3. DMSEL cdib, LQPADD 


DMSEL (out) initializes the operation. 
DMOUT accepts user data records sequentially and adds 
them to the end of the module being generated. The 
“user issues as many calls as required. 
DMSEL (ADD) completes the Goetation by adding the 
4 . module to the file. All required directory indices 

e | are created by abeary ueiiities on this cali. “4 
‘a module exists with the same name, it is deleted. 
When this call-is omitted, this is the result: | 
‘ © the module is not added to the file 


oO a module with the same name is not deleted 


o the integrity of the file is maintained 











2.4 








Deleting a2 Library Module 


To delete a library, use the DMSEL macro: 


. “hy (e | 
DMSEL filename, LY; DEL, nemermtype 


Interrogating a Library Directory 


(To be described in a later revision). 
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Design Trade-Offs and Product Objectives 
The goals in providing library utilities through a 
CDI interface are: ~ 


1. To provide a standard interface consistant with 


- other data management. interfaces. We can eventually 





allow users to use library utilities (which we never have 
had before). The interface is easily learned as it 


is a derivative of the CDI system standard. 


2. To seawide device independence for sequential source 
INPUT/OUTPUT users. Some of the special commands 
(such as SELECT module Aanecroe input) should be 
optionally done sutomatiearly as part of OPEN. 

. This would require more. information on the job 
control device allocation set. It would allow 
users to use the sam? routine to read/write from 


either a sequential device or a library element. 














4.1 


4.1.1 


4.1.1.1 


- Interface Description 


User Interface 
Declarative Macros © 


CDIB Macro 

The CDIB is the controlling block for any iieeeiy 
operation in progress. Its use is consistent with 
the data management interface. His format is: 


filename CDIB 


..The format of the CDIB7is defined in CS-14. 
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4.1.1.2 RIB Macro 


OCPERAND 


label RIB EXC 
: ,»ACCESS= EXCR 


. SHR A 
ra 2 . : : » BFSZ= : n 


[ nina=sya03] # 
[. TOA1=synbol| | 
[ ,Torc=(r) 7 


| 3 NO 
; - . |,NWAIT= Yes 
® | + | ,ReS2= a 


baa NO 








ZES 





2 é Used for MIRAM library files only. 
All parameters are optional. Omitted naa netees dake 
on the underlined value. 
The INDA and IOA1 parameters are not required, either. 
If they ere omitted, the required space will be acquired 
‘from dynamic main storage. If they are specified, they 
are subject to the constraints: 
o For SAT library files, INDA is ignored and unused 
o For MIRAM library files,. either specify both INDA 
and IOAl1L, or omit Beth: When you specify them, the 
INDA buffer must immediately precede and be contigicus 
to the IOAL buffer in main storage. 


- 














Parameters: 


ACCESS=option 


BFS2=f 256} 
n 


INDA=symbol 


- LOAl=symbol 
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defines the disk file lock used. 
(See CS-14 for details). 


The disc buffer size (parameter IOA1). 


_It must be a multiple of 256. 


The symbolic address of the index 


_ processing buffer. It must be half- 


word aligned. Its length is 256 

bytes. 

The symbolise: Radress Ge the disk buffer. 
It must be halfword aiiconed: 

ris the general register used to 

point to the current pasoca when the 
user is not using a workarea. This 
parameter is ignored if work=yes 


. 


is specified. 


Specifies whether to return on a file 


lock error. (See CS-14 for details). 
The size of the user's work area (where 
records are returned). It should be as 
large as the largest record expected. 
Specifies whether records are to be 
placed in the workarea. If NO is 
specified, records will be pointed 

to by IORG. (Note: Source-records 
will only be expanded when YES is 
specified, 


- 


eect seen 
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Imperative Macros 


DMSEL Macro Format 
| (o): 

ADD . : 
&,} DEL fide fistring 
DMSEL cdib, LY IN ABLEMENT="( °° TAG * Ji, “TYPE="" { “TAG. 

-S NEXT : 
out 

ADD - add the current module being created to the file. 


This causes the required directory indices to be 


created. (Keywords ELEMENT, TYPE do not apply). 


DEL - delete the named module from the file. This 


eliminates all directory indices for the module 
and marks the module header as inactive’. 
IN - initialize the input of the named module. (This 


call is required before DMINP macro calls are 


eae | permitted.) The module headef record is placed 


in the buffer area. 
NEXT - initialize the input of the next module in the 
| file. (This call_is required before DMINP Raczs 
calls are permitted.) The module header is placed 
in the buffer area. | | 
(Note: if a BOG or EOG is the next file item, it 


will be returned). 


OoUT - initialize the output of the named module. (This 


call is required before DMOUT macro calls are 


permitted.) 
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Oo ee we ee 


Where a "named eae ‘is required, it is apeet tied 


ad in BeEAQiC 
- gad Eatin tive Go-SLEMENT—and~TYPE. 
ELEMENT -~ the 8 character library module/group name 






a , e TYPE - the four character library module/group name ¢ 
: are aia eae 1u byte 
They canbe=specifiied=as a*string (theeaetual—reme+in 
quotes)-orethe.tagof the area-containing—them-may-be 
specified? 
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DM INP/DMOUT Imperative Macros 


The DMINP macro makes a record Ayatiabie for processing 

The DMOUT macro adds a new record to the Tibeaxe module 
being created. Both macros. are generalized imperatives 

that can be used to request records from all data management 
processors. : 


Their format is: 





NAME ‘OPERATION OPERAND 





pDMOUT 


1 g 








Parameters: 

edib the symbolic address of the CDIB that 

‘ i corresponds to the similarly named File 
assigned through job control. 

workarea specifies a user defined srk area that 


will contain the record tr=nu. cred. 


For DMINP, a retrieved record is placed in the workarea 


if WORK=YES is Spe ereeede Otherwise the record remains 


le 


.in the IOAl buffer and is pointed to co register IORB. 


For DMOUT, the user places records to be output in 


the workarea. 








4.3. 


5.1 


5.2 





5.3 


6.0 


5.0 . 


Operator Interfaces 


N/A 


Data Bases 

The proposed structure of the MIRAM library file will 
be presented in an appendix. 

The definition of the SAT library file structure 


exceeds the scope of this document. 


Environment Characteristics 


Hardware Required 


Unknown. 


Restrictions 
The MIRAM libraries (ané@ library utilities) exist 
only in the CDI environment. MIRAM libraries will 


in inaccessable in the DTF only system. 


Compatibility 


N/A 


‘ARM 


To be supplied. 








9.0 


10.0. 
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Performance 


To be supplied. 


Standards 


To be supplied. 


Standards Deviations 


N/A 


Documentation 


N/A 


Support 


N/A 
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. Appendix A Proposed Structure for MIRAM Libraries: 


This format for MIRAM library files is based on the 


Nailos - Holt - Synder letters (10/17/78 -— 11/20/78). 


Data Partition . 
mhe- aka. parkition will consist 6F 256 byte Fixed Tengen 
non-keyed records. Neither deleted records foe mixed 
* ; keyed/non keyed records will be used. It is felt that 
| neither feature is required and their inclusion would 
‘require a one byte record control block (RCB) if Bach 
record. The RCB would ieesk otherwise contiguous text 
@ Gata (for block modules) and unnecessarily complicate 


the design. 


A module consists of a set of Soneiguote Biseke The 
first block is the header block, which occupies cue 
full block and contains the number of blocks in the 
module. The next block (or blocks) contains the 
module data. All pointers within the module which 
point to blocks ‘within the module are relative to the 
module itsel£. Copying the module from one file to 


another can be block for block without modification. 
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The first module will be written starting in the first 





block of the data partition, followed by an ENDLIB Kiodk: 
When a second module is created, its header will be 
ee _ written in to the same block as the ENDLIB and a) ew 
one ENDLIB written at the end of the module. There 
“should only be one EDNLIB block in every file. 
The header block format is the same for all module 
types as well as BOG/EOG records and contains these 
fields: | 
©. Module (or group) name 
& ; 0 Module type 
. o Number of blocks occupied by this module 
o Flags: - status (deleted/active) 
~- index item (yes/no) 
~ uniqueness (yes/no) 
‘- © Number of blocks in module 
© Block (module relative) displacement of data/ 
text blocks. 


o Number of text bytes 





















MODULE : 


“Directory Partition 


* The directory is a set of MIRAM indices naineatied by 


MIRAM and nani suet ‘through index- only operations by 
library utilities. — Indices are aetavavued lexically 
ordered. Since none of the data records are keyed, 
‘library utilities will be aware of the directory 
entries necessary foecesen module and add each using 


an index-only write. 
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.BOG/EOG records occupy an entire block and have the same 
format ae a header record (roughly) with these exceptions: 
o ‘Group Name is the module name - 
° "BOG! or 'EOG! is the module type 
o Number of module blocks is one 
o The unique flag is not set (allowing multiple - 


groups of the same name) 





